<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <link href="prettify.css" type="text/css" rel="stylesheet" />
    <link href="styles.css" type="text/css" rel="stylesheet" />
    <script type="text/javascript" src="prettify.js"></script>
    <title>Patterns for Period values</title>
  </head>
  <body onload="prettyPrint()">
    <h1>Patterns for Period values</h1>
    <p>Currently, the <a href="../api/html/T_NodaTime_Period.htm"><code>Period</code></a> type doesn't support custom patterns, but two predefined patterns
which are exposed in <a href="../api/html/T_NodaTime_Text_PeriodPattern.htm"><code>PeriodPattern</code></a>:</p>

<h2>Roundtrip (<code>PeriodPattern.RoundtripPattern</code>)</h2>

<p>This pattern performs no normalization of the period - it simply writes out the value of each component of the period
(as determined by its units). The format aims to be at least <em>reminiscent</em> of ISO-8601, and in many cases it will be compatible
with ISO-8601, but it shouldn't be used in places where ISO compliance is required.</p>

<p>The format is:</p>

<pre class="prettyprint"><code>P (date components) T (time components)
</code></pre>

<p>Where each non-zero component within the period is specified as its value followed by a unit specifier from this list:</p>

<ul>
<li><code>Y</code> (years)</li>
<li><code>M</code> (months in the date portion)</li>
<li><code>W</code> (weeks)</li>
<li><code>D</code> (days)</li>
<li><code>H</code> (hours)</li>
<li><code>M</code> (minutes in the date portion)</li>
<li><code>S</code> (seconds)</li>
<li><code>s</code> (milliseconds)</li>
<li><code>t</code> (ticks)</li>
</ul>

<p>The <code>T</code> is omitted if there are no time components.</p>

<p>This format differs from ISO-8601 in the following ways:</p>

<ul>
<li>Values are <em>always</em> integers; the ISO value of <code>PT10.5S</code> is invalid in this pattern, for example</li>
<li>Values can be negative</li>
<li>The <code>s</code> and <code>t</code> units aren't part of ISO</li>
</ul>

<h2>Normalized ISO-like (<code>PeriodPattern.NormalizedIsoPattern</code>)</h2>

<p>This pattern normalizes the week, day and time parts of the period before formatting (even if the period
only contains weeks, currently), assuming that a week is always 7 days and a day is always 24 hours. The result of the normalization
removes weeks entirely, so a period of 2 weeks becomes 14 days. The month and year components are left alone, as they may vary in duration.
The result of the normalization is then serialized in a way which is <em>mostly</em> compatible with ISO-8601.</p>

<p>The general format is as for the roundtrip pattern, but without the <code>s</code> and <code>t</code> units; weeks are currently never formatted
due to normalization.</p>

<p>Only non-zero components are formatted. The exception to this is the zero
period, which is formatted as "P0D".</p>

<p>Any fractional seconds are formatted using a period as a decimal separator, with a leading 0 if necessary. So
for example, a 500 millisecond period is formatted as <code>PT0.5S</code>.</p>

<p>While this pattern is more ISO-like than the roundtrip pattern, it can still <em>produce</em> a text representation which is not valid in ISO,
as it values may be negative. Any valid ISO representation can be <em>parsed</em> correctly, however.</p>

<h2>Methods on <code>Period</code></h2>

<p>At the time of this writing, there are no methods performing parsing within <code>Period</code>, and only the parameterless <code>ToString</code> method is
supported, which always uses the roundtrip pattern described above. If patterns based on text representations are ever supported, these
methods will be implemented on <code>Period</code> in the normal way.</p>

  </body>
</html>
